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A new package of IO routines is available. It was designed 
with the following goals in mind. 


1. It should be similar in spirit to the earlier Portable Li- 
brary, and, to the extent possible, be compatible with it. 
At the same time a few dubious design choices in the Port- 
able Library will be corrected. 


xs It must be as efficient as possible, both in time and in 
space, so that there will be no hesitation in using it no 
matter how critical the application. 


3% It must be simple to use, and also free of the magic 
numbers and mysterious calls the use of which mars the un- 
derstandability and portability of many programs using older 
packages. 


4, The interface provided should be applicable on all 
machines, whether or not the programs which implement it are 
directly portable to other systems, or to machines other 
than the PDP11 running a version of Unix. 


It is intended that this package replace the Portable Li- 
brary. Although it is not directly compatible, as discussed 
below, it is sufficiently similar that a set of relatively small, 
inexpensive adaptor routines exist which make it appear identical 
to the current Portable Library except in some very obscure de- 
tails. 


The most crucial difference between this package and the 
Portable Library is that the current offering names streams in 
terms of pointers rather than by the integers known as ‘file 
descriptors.' Thus, for example, the routine which opens a named 
file returns a pointer to a certain structure rather than a 
number; the routine which reads an open file takes as an argument 
the pointer returned from the open call. 
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General Usage 
Each program using the library must have the line 

#include <stdio.h> 
which defines certain macros and variables. The library contain- 
ing the routines is ~/usr/lib/libS.a,' so the command to compile 
is 

ce Sve ne -1S 
All names in the include file intended only for internal use be- 
gin with an underscore ~_' to reduce the possibility of collision 


with a user name. The names intended to be visible outside the 
package are 


stdin The name of the standard input file 
stdout The name of the standard output file 
stderr The name of the standard error file 
EOF is actually -1, and is the value returned by the read 


routines on end-of-—file or error. 


NULL is a notation for the null pointer, returned by 
pointer-valued functions to indicate an error 


FILE expands to “struct _iob' and is a useful shorthand 
when declaring pointers to streams. 


BUFSIZ is a number (viz. 512) of the size suitable for an [IO 
buffer supplied by the user. See setbuf, below. 


getc, getchar, putc, putchar, feof, ferror, fileno 
are defined as macros. Their actions are described 
below; they are mentioned here to point out that it is 
not possible to redeclare them and that they are not 
actually functions; thus, for example, they may not 
have breakpoints set on them. 


The routines in this package, like the current Portable Li- 


brary, offer the convenience of automatic buffer allocation and 
output flushing where appropriate. Absent, however, is the fa- 
cility of changing the default input and output streams by as- 
signing to `cin' and `cout.' The names ‘stdin,' stdout,' and 


“stderr' are in effect constants and may not be assigned to. 
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Calls 


The routines in the library are in nearly one-to-one 
correspondence with those in the Portable Library. In several 
cases the name has been changed. This is an attempt to reduce 
confusion. If the attempt is judged to fail the names may be 
made identical even though the arguments may be different. The 
order of this list generally follows the order used in the Port- 
able Library document. 


FILE *fopen(filename, type) 
char *filename, *type; 
Fopen opens the file and, if needed, allocates a buffer for it. 


Filename is a character string specifying the name. Type is a 
character string (not a single character). It may be *"r",! 

Wyte or “tam to indicate intent to read, write, or append. 
The value returned is a file pointer. If it is null the attempt 


to open failed. 


FILE *freopen(filename, type, ioptr) 

char *filename, *type; 

FILE *ioptr; 

The stream named by ioptr is closed, if necessary, and then reo- 
pened as if by fopen. If the attempt to open fails, NULL is re- 
turned, otherwise ioptr, which will now refer to the new file. 


Often the reopened stream is stdin or stdout. 


int getc(ioptr) 

returns the next character from the stream named by ioptr, which 
is a pointer to a file such as returned by fopen, or the name 
stdin. The integer EOF is returned on end-of—file or when an er- 
ror occurs. The null character is a legal character. 


int fgetc(ioptr) 
is identical in function to `getc' but is a genuine function, not 
a macro. 


putce(c, ioptr) 

Putc writes the character c on the output stream named by ioptr, 
which is a value returned from fopen or perhaps stdout or stderr. 
The character is returned as value, but EOF is returned on error. 


fputc(c, ioptr) 
Fpute is identical in function to “putc' but is a genuine func- 
tion, not a macro. 


fclose (ioptr) 

The file corresponding to ioptr is closed after any buffers are 
emptied. A buffer allocated by the IO system is freed. Felose 
is automatic on normal termination of the program. 
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fflush (ioptr) 

Any buffered information on the (output) stream named by ioptr is 
written out. Output files are normally buffered if and only if 
they are not directed to the terminal, but stderr is unbuffered 
unless setbuf is used. 


exit (errcode) 
Exit terminates the process and returns its argument as status to 


the parent. This is a special version of the routine which calls 
fflush for each output file. To terminate without flushing, use 
exit. 

feof (ioptr) 


returns non-zero when end-of-file has occurred on the specified 
input stream. 


ferror (ioptr) 

returns non-zero when an error has occurred while reading or 
writing the named stream. The error indication lasts until the 
file has been closed. 


getchar( ) 
is identical to ‘getc(stdin)'. 


putchar (c) 
is identical to `putce(c, stdout)'. 


char *gets(s) 

reads characters up to a new-line from the standard input. The 
new-line character is replaced by a null character. It is the 
user's responsibility to make sure that the character array s is 
large enough. Gets returns its argument, or null if end-of-file 
or error occurred. Note that this routine is not compatible with 
fgets; it is included for downward compatibility. 


char *fgets(s, n, ioptr) 
reads up to n characters from the stream ioptr into the character 


pointer s. The read terminates with a new-line character. The 
new-line character is placed in the buffer followed by a null 
pointer. The first argument, or a null pointer if error or end— 


of-file occurred, is returned. 


puts (s) 
writes the null-terminated string {character array) s on the 
standard output. A new-line is appended. No value is returned. 


Note that this routine is not compatible with fputs; it is in- 
cluded for downward compatibility. 


Eputs(s, ioptr) 
writes the null-terminated string (character array) on the stream 
s. No new-line is appended. No value is returned. 
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ungetc(c, ioptr) 
The argument character c is pushed back on the input stream named 


by ioptr. Only one character may be pushed back. 


printf(format, al, .. .) 
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